From 00e738c142451c2a7e06817f07745f2f2ab05d28 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Fri, 5 Oct 2001 01:53:04 +0000 Subject: [PATCH] fix GtkImage overview 2001-10-04 Havoc Pennington * gtk/tmpl/gtkimage.sgml: fix GtkImage overview --- docs/reference/ChangeLog | 4 + docs/reference/gtk/tmpl/gtkimage.sgml | 113 +++++++++++++++++++---- docs/reference/gtk/tmpl/gtksettings.sgml | 4 +- 3 files changed, 102 insertions(+), 19 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 2c4975c0cf..416106d08f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2001-10-04 Havoc Pennington + + * gtk/tmpl/gtkimage.sgml: fix GtkImage overview + Wed Oct 3 15:09:18 2001 Jonathan Blandford * gtk/gtk.types: remove gtk_cell_editable_get_type diff --git a/docs/reference/gtk/tmpl/gtkimage.sgml b/docs/reference/gtk/tmpl/gtkimage.sgml index 7c9a6e400f..59e898d5e1 100644 --- a/docs/reference/gtk/tmpl/gtkimage.sgml +++ b/docs/reference/gtk/tmpl/gtkimage.sgml @@ -2,23 +2,101 @@ GtkImage -A widget displaying a graphical image +A widget displaying an image -The #GtkImage widget displays a graphical image. The image is typically created -using gdk_image_new. - - -The pixels in a #GtkImage may be manipulated by the application after creation, -as #GtkImage store the pixel data on the client side. If you wish to store the -pixel data on the server side (thus not allowing manipulation of the data after -creation) you should use #GtkPixmap. +The #GtkImage widget displays an image. Various kinds of object +can be displayed as an image; most typically, you would load a +#GdkPixbuf ("pixel buffer") from a file, and then display that. +There's a convenience function to do this, gtk_image_new_from_file(), +used as follows: + + GtkWidget *image; + image = gtk_image_new_from_file ("myfile.png"); + +If the file isn't loaded successfully, the image will contain a +"broken image" icon similar to that used in many web browsers. +If you want to handle errors in loading the file yourself, +for example by displaying an error message, then load the image with +gdk_pixbuf_new_from_file(), then create the #GtkImage with +gtk_image_new_from_pixbuf(). + + +The image file may contain an animation, if so the #GtkImage will +display an animation (#GdkPixbufAnimation) instead of a static image. + + +#GtkImage is a subclass of #GtkMisc, which implies that you can +align it (center, left, right) and add padding to it, using +#GtkMisc methods. + + +#GtkImage is a "no window" widget (has no #GdkWindow of its own), +so by default does not receive events. If you want to receive events +on the image, such as button clicks, place the image inside a +#GtkEventBox, then connect to the event signals on the event box. +For example, here is some code that handles button press events +on a #GtkImage: + + static void + button_press_callback (GtkWidget *event_box, + GdkEventButton *event, + gpointer data) + { + g_print ("Event box clicked at coordinates %d,%d\n", + event->x, event->y); + + /* Returning TRUE means we handled the event, so the signal + * emission should be stopped (don't call any further + * callbacks that may be connected). Return FALSE + * to continue invoking callbacks. + */ + return TRUE; + } + + static GtkWidget* + create_image (void) + { + GtkWidget *image; + GtkWidget *event_box; + + image = gtk_image_new_from_file ("myfile.png"); + + event_box = gtk_event_box_new (); + + gtk_container_add (GTK_CONTAINER (event_box), image); + + g_signal_connect (G_OBJECT (event_box), + "button_press_event", + G_CALLBACK (button_press_callback), + image); + + return image; + } + + + +When handling events on the event box, keep in mind that coordinates +in the image may be different from event box coordinates due to +the alignment and padding settings on the image (see #GtkMisc). +The simplest way to solve this is to set the alignment to 0.0 +(left/top), and set the padding to zero. Then the origin of +the image will be the same as the origin of the event box. + + + +Sometimes an application will want to avoid depending on external data +files, such as image files. GTK+ comes with a program to avoid this, +called gdk-pixbuf-csource. This program +allows you to convert an image into a C variable declaration, which +can then be loaded into a #GdkPixbuf using +gdk_pixbuf_new_from_inline(). -#GtkPixmap, #GdkRgb +#GdkPixbuf @@ -30,12 +108,13 @@ below. -Describes the representation stored by a #GtkImage. If you want to get the image -from the widget, you can only get the currently-stored representation. e.g. if -the gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can call -gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty images, you can -request any storage type (call any of the "get" functions), but they will all -return %NULL values. +Describes the image data representation used by a #GtkImage. If you +want to get the image from the widget, you can only get the +currently-stored representation. e.g. if the +gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can +call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty +images, you can request any storage type (call any of the "get" +functions), but they will all return %NULL values. @GTK_IMAGE_EMPTY: there is no image displayed by the widget @@ -44,7 +123,7 @@ return %NULL values. @GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf @GTK_IMAGE_STOCK: the widget contains a stock icon name @GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet -@GTK_IMAGE_ANIMATION: +@GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml b/docs/reference/gtk/tmpl/gtksettings.sgml index b1a9195c3a..d246ff91f1 100644 --- a/docs/reference/gtk/tmpl/gtksettings.sgml +++ b/docs/reference/gtk/tmpl/gtksettings.sgml @@ -191,12 +191,12 @@ GtkSettings - + - + -- 2.30.2